home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / amok_lha / amok17.lha / AmokPoster next >
Text File  |  1993-08-15  |  8KB  |  154 lines
  1. ======================================================================
  2.                 AMOK - Amiga Modula Klub Stuttgart
  3.      "AmokPoster": Norm bzw. Standardform für Amok-Beiträge
  4.           Tips und Anhaltspunkte für Veröffentlichungen
  5. ======================================================================
  6.  
  7. Einleitung
  8. ----------
  9. Wir - Amok - sind gerne bereit, auch anderen Modula-2-Programmierern
  10. mit den Amok-Disks einen Weg zur Veröffentlichung ihrer Programme zu
  11. bieten. Ziel unserer PD-Reihe ist es schließlich, für eine möglichst
  12. weite Verbreitung von Modula zu sorgen. Da sich Modula als Programmier-
  13. sprache optimal zum Austausch von Programm-Modulen eignet, kann jeder
  14. Modula-Programmierer hierzu beitragen. Je größer die Modulbibliothek
  15. ist, auf die ein Programmierer zurückgreifen kann, desto weniger muß
  16. er sich mit zeitraubenden Alltagsproblemen herumschlagen und sozusagen
  17. "das Rad zweimal erfinden".
  18. Falls Sie also Module geschrieben haben, von denen Sie denken, daß auch
  19. andere sie gebrauchen können, schicken Sie sie an Amok. Wenn irgend
  20. möglich werden wir den Beitrag in unsere Amok-PD-Reihe aufnehmen. Wir
  21. stellen zwar keine Ansprüche an die Genialität der Programme, damit
  22. Ihr Beitrag eine Chance hat, veröffentlicht zu werden, sollten Sie aber
  23. die unten aufgeführten Punkte beachten. Damit ist gewährleistet, daß
  24. die PD-Software auch wirklich brauchbar ist.
  25.  
  26. 1) Kriterien
  27. ------------
  28. Wie schon erwähnt stellen wir keine Anforderungen an das, was ein Programm
  29. besonderes kann. Das was es kann, soll es aber sinnvoll und korrekt aus-
  30. führen. Ein simples aber nützliches Modul hat, auch wenn es noch so banal
  31. ist, höhere Chancen, veröffentlicht zu werden, als ein Riesenprojekt, das an
  32. sich genial ist, aber ständig guru-meditiert.
  33.  
  34. 2) Amok Anforderungen
  35. ---------------------
  36. Die Folgenden Punkte sind verbindlich und von jedem Amok-Beitrag einzuhalten:
  37.  
  38. * Zu jedem Modul(-packet) gehört eine Dokumentation. Ohne Dokumentation
  39.   sind die Module für andere unbrauchbar. Es gibt auf den Amok-Disketten
  40.   folgende Formen der Dokumentation:
  41.     - Dokumentation im Klartext in einer extra Datei mit der Endung ".dok"
  42.       (für deutsche Dokumentation) oder ".doc" (für die englische)
  43.     - stichwortartige Kurzbeschreibung der Prozeduren im Definitionsmodul
  44.       Diese Form der Dokumentation ist auf Amok#7 bei "ProgInfo"
  45.       (StandardIDs) genauer beschrieben.
  46.   Die Dokumentation sollte mindestens diese Informationen beinhalten:
  47.     - Bedeutung und Auswirkung der Prozedurparameter
  48.     - Funktion und Verwendungszweck der Prozeduren
  49.     - Bedeutung der Rückgabewerte der Prozeduren
  50.     - Wichtige Hinweise über exportierte Variablen, Konstanten und Typen
  51.     - Hinweise auf mögliche Fehler (soweit bekannt)
  52.     - Angaben über eventuelle Einschränkungen oder Warnungen
  53.   Wenn möglich sollte die Dokumentation nur aus reinem ASCII-Code ohne
  54.   Steuer- oder Formatsequenzen bestehen (Type-, More-, m2emacs- und
  55.   copy-to-prt:-verträglich)
  56.  
  57. * Der Source-Code sollte den Modulen immer beigefügt werden. Schließlich
  58.   sollen andere Programmierer aus Ihrem Programm etwas lernen können.
  59.   Außerdem ist es somit möglich, eventuelle Fehler zu verbessern oder
  60.   das Programm an eigene Bedürfnisse anzupassen. Als Ausnahmen sind
  61.   folgende zulässig:
  62.     - das Programm ist wirklich ausgesprochen genial und gehört eigentlich
  63.       patentiert (es muß natürlich absolut fehlerfrei sein)
  64.     - die Module sind Teile eines von Ihnen kommerziell vertriebenen
  65.       Programms, und sie wollen nicht, daß jemand Einblick erhält
  66.     - Ihr Programmierstil ist so schlecht und Ihre Methoden so haar-
  67.       sträubend, daß sie den Source-Code niemandem zumuten wollen
  68.       (In diesem Fall sollten Sie sich allerdings Überlegen, ob Sie nicht
  69.       lieber C oder Assembler programmieren wollen)
  70.  
  71. * Definitions und Implementationsmodul sollten unseren Modulkopf (siehe
  72.   irgendein Amok-Modul) beinhalten. Dieser ist zur leichteren Verwaltung
  73.   der inzwischen mehrere Megabyte umfassenden Amok-Softwarebibliothek
  74.   notwendig. Er wird auf Amok#7 bei "ProgInfo" (StandardIDs) genauer
  75.   beschrieben.
  76.  
  77. * Alle Dateien und Unterdirectories sollen Icons haben, sodaß sie von der
  78.   Workbench aus zugänglich sind. Das Default-Tool (mit "Info" aus dem WB-
  79.   Menu einstellbar) von Textdateien (Source und Dokumentation) muß auf
  80.   ":C/MUCHMORE" eingestellt sein.
  81.  
  82. 3) Amok Vereinbarungen
  83. ----------------------
  84. Es wird gebeten, auch auf folgendes zu achten:
  85.  
  86. * Sollten zum Compilieren eines Moduls noch andere nicht standardmäßige
  87.   Module benötigt werden, sollten diese mitgeliefert werden. Dabei ist
  88.   darauf zu achten, daß die sym-Schlüssel stimmen, d.h. alles mit der
  89.   selben Version der Definitionsmodule compiliert wurde. Existieren von
  90.   imortierten Modulen mehrere Versionen, dann ist anzugeben, welche
  91.   benötigt wird.
  92.  
  93. * Im Source-Code und in der Dokumentation sollte man wenn möglich die
  94.   Zeilenlänge auf 70 bis 75 Zeichen begrenzen. M2emacs und MuchMore
  95.   akzeptieren zwar 80 Zeichen, viele möchten jedoch sicherlich die
  96.   Texte ausdrucken, und da ist ein Rand ganz nützlich.
  97.  
  98. * Prozedur-, Variablen-, Konstanten- und Typenbezeichner sollten
  99.   vorzugsweise englisch sein, ebenso die Kurzbeschreibung der Prozeduren
  100.   im Definitionsmodul (siehe Amok#7, ProgInfo/StandardIDs).
  101.   Wenigstens sollte man Englisch und Deutsch nicht mischen.
  102.   Deutsche Dokumentation sollte nicht fehlen, englische ist freiwillig.
  103.  
  104. * Kleine Demoprogramme dienen der leichteren Verständnis und dem besseren
  105.   Einarbeiten in die Funktionen eines Moduls. Oft sind Testmodule oder
  106.   sonstige Beispielanwendungen als Nebenprodukte eigener Programme
  107.   sowieso vorhanden.
  108.  
  109. * Seien Sie fair gegenüber anderen Programmierern. "Public Domain" heißt
  110.   noch lange nicht "Software-Freiwild". Wenn Sie Programmteile von
  111.   anderen übernehmen, erwähnen sie den Autor bitte im Modulkopf oder in
  112.   Kommentarzeilen. Für eine kommerzielle Nutzung brauchen Sie die
  113.   Schriftliche Erlaubnis des jewiligen Autors. Denken sie bitte auch
  114.   an eventuelle Shareware-Gebühren.
  115.  
  116. 4) Zum Thema korrekte Programme
  117. -------------------------------
  118. Die folgenden Anweisungen gelten nicht speziell für Amok-Disketten
  119. sondern sollten von allen Programmierern beachtet werden. Wenn diese
  120. Punkte für Sie noch nicht selbstverständlich sind, empfehlen wir Ihnen
  121. DRINGENDST ihre Programme in Zukunft dementsprechend auszulegen.
  122.  
  123. * Alle Programme sollten auf korrektem Weg verlassen werden können, das
  124.   heißt, ohne neu starten zu müssen, und so, daß uneingeschränkt weiter-
  125.   gearbeitet werden kann. Außerdem sollen sie alle Betriebsmittel und
  126.   Resourcen an das System zurückgeben (Speicher deallozieren, Fenster,
  127.   Screens und Files schließen).
  128.  
  129. * Programme sollten sich nicht so verhalten, als wären sie die einzigen
  130.   im System, sondern auf das Multitasking und seine Restriktionen
  131.   Rücksicht nehmen (z.B. gegenseitiger Ausschluß beim Zugriff auf System-
  132.   strukturen).
  133.  
  134. * Programme sollen sich gegenüber dem Benutzer logisch und bei Fehlein-
  135.   gaben robust verhalten.
  136.  
  137. * Man sollte nie davon ausgehen, immer alle Betriebsmittel zu bekommen,
  138.   die man anfordert. Programme sollen sich definiert verhalten, wenn z.B.
  139.   Files nicht geöffnet werden können, oder nicht mehr genügend Speicher
  140.   vorhanden ist.
  141.  
  142. * Die Benutzerschnittstelle soll den beim Amiga allgemein üblichen Richt-
  143.   linien entsprechen (siehe Intuition Reference Manual Chapter 12: Style).
  144.  
  145. * Programme sollten wenn möglich keine spezielle Gerätekonfiguration
  146.   vorraussetzen.
  147.  
  148. * Besonders für die Entwicklung zukünftiger Bibliotheksmodule ist wichtig,
  149.   daß die Prozeduren reentrant sind, falls es sinnvoll ist, sie von
  150.   mehreren Tasks aus gleichzeitig zu benutzen (es ist in Modula ja nicht
  151.   möglich, Module zweimal zu importieren).
  152.  
  153. Wir freuen uns aber trotzdem über jegliche Software !!!
  154.